                              
                              
                   PsiWin translation API
                              
                              

Overview
  
  General
PsiWin includes a standalone file translation library. Using
the API to this library, a legitimate owner of PsiWin can
programmatically translate DOS and Windows application files
to appropriate Psion formats, or vice versa.
The file converters themselves are part of PsiWin and may
not be redistributed in any form.
This API information is supplied "as-is" and is unsupported.
Psion disclaim any liability for the use of this
information.
Sample 'C' code is provided in CONVERT.TXT, and BASIC in
CONVERT.BAS.
(The file format translation library can also be extended by
third-parties to support new DOS, Windows and Psion
application file formats. This is not described here.)
  
  Translation Paths
Each file format translator or translation path supports the
translation of files between one PC application file format
and one Psion native file format.  Applications that use
compound file formats, such as Lotus Organizer are supported
by more than one translator, each one handling one inherent
Lotus Organizer format, such as the Calendar and one Psion
native format, such as the Agenda.
  
  Terminology
The API uses the following conventions:
 App - PC Application
 Format - PSION Formats
 Path - Translation Paths
  
  Selecting a Translation Path
The selection of a translation path is accomplished by using
information about the files to be translated and the formats
they are to be translated into to select a unique
translator.  For example, to import a PC file, the
translation manager would:
 1.    Initialise the Translators - XMOpen
 2.    Set the translation direction - XMSetDirection
 3.    Get the translators to examine the file -
   XMSelectApp
 4.    The file may be recognised by more than one
   converter - e.g. there are two text formats (DOS and
   Windows have different character sets). If this is the
   case the application must select the appropriate format
   - use XMGetAppName and XMSetApp functions to do this.
 5.    At this stage the source has been uniquely
   determined. Now it's possible that the selected file
   could be converted to one or more formats. Use
   XMCountFormats and XMGetFormatInfo to find out what the
   choices are.
 6.    At last the translation Path can be uniquely
   determined. - XMSetPath
 7.    Check the transfer modes available to this
   translation path with XMGetTransferMode
 8.    Import the file and check the error return. -
   XMImport, XMGetLastErrorMsg
 9.    It's done - use XMClose to sign off.
Throughout the translator selection process, PsiWinXM
maintains three lists: one of possible PC applications, one
of possible PSION native formats and one of possible
translation paths.  If the source file and direction alone
are not sufficient to select a unique translation path, the
API can provide the names of remaining possible PC
applications and/or Psion native formats for the user to
make a selection.
Note: since at any point in the conversion process you can
obtain a list of the available translation paths, it is
possible to avoid steps 4 and 5 by listing the available
paths and picking one - using XMCountPaths, XMGetPathInfo
and XMSetPath. As, in step 4, the source app has been
chosen, there are the same number of Paths as Formats so the
Format number corresponds to the path wanted.
  
  Performing a translation
Once a translation path and result file name has been
selected, PsiWinXM is directed to run the translation,
either Importing to a Psion native format or exporting to a
DOS or Windows application format.  During the translation,
the translator will periodically callback to the Hosting
application to report translation progress and accept the
user's request to cancel the translation.  Should an error
occur during translation, the hosting application is
notified and can retrieve an error message from PsiWinXM.

API Calls
  
  Initialization
  HXM XMOpen(LPSTR psionName, LPSTR xlateFolder, HWND
  hParent)
XMOpen initialises a connection with the translation
manager.  PsiWinXM searches the indicated xlateFolder for
translator and translator preference modules.  The psionName
is used to track any preferences or past usage patterns by
user.  If psionName is NULL, a "Guest" user will be assumed.
hParent identifies a window to "own" any dialogs that may be
created by PsiWinXM's translators or preference components.
XMOpen returns a global handle to be used in subsequent
calls to the translation manager.  If the initialisation
fails for any reason, XMOpen returns a NULL handle.
  BOOL XMClose(HXM hXM)
XMClose terminates the connection with the translation
manager represented by the connection handle hXM and
releases any resources associated with the connection.
XMClose returns TRUE if the termination is successful and
FALSE otherwise.
  
  Queries
Often, the user must make a selection of Psion format or PC
application to work with.  The following query functions are
provided to support the generation of lists from which to
make a selection.
  int XMCountFormats(HXM hXM)
XMCountFormats returns the number of possible Psion formats
at this stage of the translator selection.
  BOOL XMGetFormatInfo(HXM hXM, int nFormat, PFINFO FAR
  *lpinfo)
XMGetFormatInfo fills in the PFINFO structure with details
about the nFormat'th possible Psion format.  This structure
includes the name of the Psion application as well as the
filename extension it uses and its default document
directory.
  int XMCountApps(HXM hXM)
XMCountApps returns the number of possible PC application
formats at this stage of the translator selection process.
  int XMGetAppNameLen(HXM hXM, int nApp)
XMGetAppNameLen returns the length of the bytes of the PC
application name corresponding to nApp.  nApp identifies one
of the pssible PC applications at this stage of the
translator selection process.
  int XMGetAppName(HXM hXM, int nApp, LPSTR appName, int
  nName)
XMGetAppName returns the PC application name corresponding
to nApp in the buffer appName up to a maximum of nName
characters.  XMGetAppName returns the length of the C string
copied to appName.
  int XMGetFilterLen(HXM hXM)
XMGetFilterLen returns the length of the COMMDLG filter
string representing the current set of possible PC
applications.
  int XMGetFilter(HXM hXM, LPSTR filterBuf, int nFilter)
XMGetFilter returns the current COMMDLG filter in filterBuf
up to a maximum of nFilter characters.  XMGetFilter returns
the number of characters actually returned in filterBuf.
  int XMCountPaths(HXM)
XMCountPaths returns the number of possible translators at
this stage of the translator selection process.
  BOOL XMGetPathInfo(HXM hXM, int nPath, XMPATH FAR
  *lpinfo)
XMGetPathInfo fills in the XMINFO structure with details
about the nPath'th possible translator at this stage of the
translator selection process.  The information provided
includes the names and indexes of the PC application and
Psion format handled by this translator as well as a set of
flags indicating translator attributes.
  
  Selecting a translator
The selection of a specific translator is accomplished by
reducuing the available choices until only one remains.  The
choices can be reduced by specifying the direction of
transfer and the file formats to be exchanged.  When the
file to be transfered is known, it also can be examined to
restrict the choice of translators.
The following calls support this narrowing process.
  BOOL XMSetDirection(HXM hXM, int direction)
XMSetDirection begins the process of selecting a translator
by restricting the choice of translators to those suitable
for import or for export.  Setting the direction clears any
selections of a Psion Format or PC application to exchange.
  BOOL XMSetFormat(HXM hXM, int nFormat)
XMSetFormat further restricts the choice of translation
paths by indicating the Psion format to be exchanged.  The
direction of transfer should already be set as resetting the
direction of transfer will clear the choice of Psion format
to be exchanged.
  BOOL XMSetApp(HXM hXM, int nApp)
XMSetApp restricts the choice of translators by selecting
the PC application format to be exchanged. The direction of
transfer should already be set as resetting the direction of
transfer will clear the choice of PC application format to
be exchanged.
  int XMSelectApp(HXM hXM, LPSTR fileName)
XMSelectApp asks each currently allowed translator in turn
to examine the indicated file and answer whether or not it
can translate the file.  The return value indicates either
the number of possible translation paths left to choose from
or and indication of a problem.  A return value of  0
indicates that NO translator can handle the file.  A return
value of -1 means that the file is password protected and
therefore cannot be translated.
  int XMSelectFormat(HXM hXM, LPSTR fileName)
XMSelectFormat uses the available translation paths to
determine the Psion format of the indicated file.  The
return value will be the one-based index of the associated
Psion format if the file is recognized and can be
translated.  A return value of  0 means that this file's
format is unknown.  A return value of -1 means that the file
is password protected and therefore cannot be translated.
  BOOL XMSetPath(HXM hXM, int nPath)
XMSetPath makes the final translator selection by
identifying one of one or more translation paths.
  
  Import/Export
Once a translator has been selected, the selection is
indicated via XMSetPath.  At this point,  a result file name
for the translation will be selected.  Depending on the
transfer modes supported by the translator selected, the
result file may be handled differently.  Translators can
support one or more of the following transfer modes.
(Translators do support more than Overwrite or Append
access.  Specifically, translations to Lotus Organizer and
Act! will support both Overwrite and Append access.)
     Overwrite The translator will replace an existing file
or create a new one
     Append         The translator will add its data to an
existing file
     Merge          The translator will merge the source
file into an existing file
     Synchronize    The translator will logically
synchronize the result file with the source file.
  int XMGetTransferMode(HXM hXM)
XMGetTransferMode returns the available transfer modes for
the selected translator.
  BOOL XMImport(HXM hXM, LPSTR sourceFile, LPSTR
  resultFile,
                      int xferMode, XMSTATPROC statusRtn)
XMImport uses the current translation path to translate the
indicated file using the indicated transfer mode, the
translation is from a PC application to a Psion format.  The
statusRtn points to a routine that will be called back to
report the status of the translation as a percentage
completed and to accept a request to cancel the translation.
  BOOL XMExport(HXM hXM, LPSTR sourceFile, LPSTR
  resultFile,
                      int xferMode, XMSTATPROC statusRtn)
XMExport uses the current translation path to translate the
indicated file using the indicated transfer mode, the
translation is from a Psion format to a PC application.  The
statusRtn points to a routine that will be called back to
report the status of the translation as a percentage
completed and to accept a request to cancel the translation.
  
  Error Reporting
Most PsiWinXM API calls return FALSE in case of an error.
An appropriate error message is also accessible via the API
as follows:
  int XMGetLastErrorMsg(HXM hXM, LPSTR szMsg, int nMsg)
XMGetLastErrorMsg places an error message in szMsg of up to
nMsg characters based on the last error which has occurred
and returns the actual length of the message copied to szMsg

